import Info from 'components/Markdown/Info'

export const meta = {
  title: 'Reference',
  position: 110,
}

## Install

```sh
npm install --save prisma-binding
```

## Example

Consider the following data model for your Prisma service:

```graphql
type User {
  id: ID! @unique
  name: String
}
```

If you instantiate `Prisma` (i.e. a Prisma binding instance) based on this service, you'll be able to send the following queries/mutations:

```js
// Instantiate `Prisma` based on concrete service
const prisma = new Prisma({
  typeDefs: 'schemas/database.graphql',
  endpoint: 'https://api.graph.cool/simple/v1/my-prisma-service'
  secret: 'my-super-secret-secret'
})

// Retrieve `name` of a specific user
prisma.query.user({ where { id: 'abc' } }, '{ name }')

// Retrieve `id` and `name` of all users
prisma.query.users(null, '{ id name }')

// Create new user called `Sarah` and retrieve the `id`
prisma.mutation.createUser({ data: { name: 'Sarah' } }, '{ id }')

// Update name of a specific user and retrieve the `id`
prisma.mutation.updateUser({ where: { id: 'abc' }, data: { name: 'Sarah' } }, '{ id }')

// Delete a specific user and retrieve the `name`
prisma.mutation.deleteUser({ where: { id: 'abc' } }, '{ id }')
```

Under the hood, each of these function calls is simply translated into an actual HTTP request against your Prisma service (using [`graphql-request`](https://github.com/prisma/graphql-request)).

The API also allows to ask whether a specific node exists in your Prisma database:

```js
// Ask whether a post exists with `id` equal to `abc` and whose
// `author` is called `Sarah` (return boolean value)
prisma.exists.Post({
  id: 'abc',
  author: {
    name: 'Sarah'
  }
})
```

## API

### Prisma

#### constructor

```ts
constructor(options: PrismaOptions): Prisma
```

The `PrismaOptions` type has the following fields:

- `typeDefs` (required, `string`): File path to the schema definition of your Prisma service (typically a file called `prisma.graphql`) 
- `endpoint` (required, `string`): The endpoint of your Prisma service
- `secret` (optional, `string`): The secret of your Prisma service
- `fragmentReplacements` (optional, `FragmentReplacements`): A list of GraphQL fragment definitions, specifying fields that are required for the resolver to function correctly
- `debug` (optional, `boolean`): Log all queries/mutations to the console; default: `false`

#### query & mutation

`query` and `mutation` are public properties on your `Prisma` instance (see also the [GraphQL Binding documentation](!alias-quaidah9ph) for more info). They both are of type `Query` and expose a number of auto-generated delegate resolver functions that are named after the fields on the `Query` and `Mutation` types in your Prisma database schema.

Each of these delegate resolvers in essence provides a convenience API for sending queries/mutations to your Prisma service, so you don't have to spell out the full query/mutation from scratch and worry about sending it over HTTP. This is all handled by the delegate resolver function under the hood.

Delegate resolver have the following interface:

```js
(args: any, info: GraphQLResolveInfo | string): Promise<T>
```

The input arguments are used as follows:

- `args`: An object carrying potential arguments for the query/mutation
- `info`: An object representing the selection set of the query/mutation, either expressed directly as a string or in the form of `GraphQLResolveInfo` (you can find more info about the `GraphQLResolveInfo` type [here](http://graphql.org/graphql-js/type/#graphqlobjecttype))

The generic type `T` corresponds to the type of the respective field.

#### exists

`exists` also is a public property on your `Prisma` instance. Similar to `query` and `mutation`, it also exposes a number of auto-generated functions. However, it exposes only a single function per type. This function is named according to the root field that allows the retrieval of a single node of that type (e.g. `User` for a type called `User`). It takes a `where` object as an input argument and returns a `boolean` value indicating whether the condition expressed with `where` is met.

This function enables you to easily check whether a node of a specific type exists in your Prisma database.

#### request

The `request` method lets you send GraphQL queries/mutations to your Prisma service. The functionality is identical to the auto-generated delegate resolves, but the API is more verbose as you need to spell out the full query/mutation. `request` uses [`graphql-request`](https://github.com/graphcool/graphql-request) under the hood.

Here is an example of how it can be used:

```js
const query = `
  query ($userId: ID!){
    user(id: $userId) {
        id
      name
    }
  }
`

const variables = { userId: 'abc' }

prisma.request(query, variables)
  .then(result => console.log(result))
// sample result:
// {"data": { "user": { "id": "abc", "name": "Sarah" } } }
```
